X25519DiffieHellman agreement with byte-based public keys by vcsjones · Pull Request #128086 · dotnet/runtime

vcsjones · 2026-05-12T16:52:49Z

Contributes to #128040.

This introduces a DeriveRawSecretAgreement that does key agreement with the other party's key as a sequence of bytes instead of forcing creating the instance of X25519DiffieHellman. This reduces allocations in the typical use case of X25519.

dotnet-policy-service · 2026-05-12T16:54:36Z

Tagging subscribers to this area: @bartonjs, @vcsjones, @dotnet/area-system-security
See info in area-owners.md if you want to be subscribed.

Copilot

Pull request overview

This PR extends X25519DiffieHellman with byte-based public-key key agreement APIs and wires them through the platform implementations (OpenSSL/Apple/Windows/CNG), adding native shim entrypoints where needed, plus expanded contract and functional test coverage.

Changes:

Add DeriveRawSecretAgreement(byte[] otherPartyPublicKey) and DeriveRawSecretAgreement(ReadOnlySpan<byte> otherPartyPublicKey, Span<byte> destination) along with a new abstract DeriveRawSecretAgreementCore(ReadOnlySpan<byte>, Span<byte>).
Implement the new core overload across OpenSSL/Apple/Windows/CNG implementations and add new native entrypoints for OpenSSL and Apple to derive directly from raw public-key bytes.
Add/extend tests validating argument checks, disposal behavior, symmetry, vectors, and zero-shared-secret behavior for the new overloads.

Show a summary per file

File	Description
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X25519DiffieHellman.cs	Adds the new public overloads and new abstract core method plus length validation helper.
src/libraries/System.Security.Cryptography/ref/System.Security.Cryptography.cs	Updates the public ref surface to include the new overloads and abstract core method.
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X25519DiffieHellmanImplementation.OpenSsl.cs	Implements the new core overload and switches fallback to the new raw-public-key interop.
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X25519DiffieHellmanOpenSsl.OpenSsl.cs	Same as above for the public OpenSSL-backed type.
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X25519DiffieHellmanImplementation.Apple.cs	Implements the new core overload and routes to the new Apple bytes-based interop.
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X25519DiffieHellmanImplementation.Windows.cs	Implements the new core overload and refactors shared Windows derivation path.
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X25519DiffieHellmanCng.Windows.cs	Implements the new core overload and factors shared public-key handling.
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X25519DiffieHellmanCng.cs	Declares the new protected override in the partial type.
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X25519DiffieHellmanImplementation.NotSupported.cs	Adds the new core overload stub for unsupported platforms.
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X25519DiffieHellmanOpenSsl.NotSupported.cs	Adds the new core overload stub (currently throws `NotImplementedException`).
src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/Cng.NotSupported.cs	Adds the new core overload stub in the CNG PNSE implementation.
src/libraries/Common/src/Interop/Unix/System.Security.Cryptography.Native/Interop.EvpPkey.X25519.cs	Adds interop for the new OpenSSL native entrypoint deriving from raw public-key bytes.
src/native/libs/System.Security.Cryptography.Native/pal_evp_pkey_x25519.h	Declares `CryptoNative_X25519DeriveSecretAgreementWithPublicKey`.
src/native/libs/System.Security.Cryptography.Native/pal_evp_pkey_x25519.c	Implements the new OpenSSL helper by importing the peer key and deriving.
src/native/libs/System.Security.Cryptography.Native/entrypoints.c	Exposes the new OpenSSL entrypoint via the resolver table.
src/libraries/Common/src/Interop/OSX/System.Security.Cryptography.Native.Apple/Interop.X25519.cs	Adds interop for the new Apple bytes-based derivation export.
src/native/libs/System.Security.Cryptography.Native.Apple/pal_swiftbindings.swift	Implements `AppleCryptoNative_X25519DeriveRawSecretAgreementWithBytes` and shares logic via a helper.
src/native/libs/System.Security.Cryptography.Native.Apple/pal_swiftbindings.h	Declares the new Apple export.
src/native/libs/System.Security.Cryptography.Native.Apple/entrypoints.c	Exposes the new Apple export via the resolver table.
src/libraries/System.Security.Cryptography/tests/X25519DiffieHellmanContractTests.cs	Adds contract tests for the new overloads and adds callback plumbing for the new core method.
src/libraries/System.Security.Cryptography/tests/X25519DiffieHellmanBaseTests.cs	Adds functional tests covering new overloads (symmetry, vectors, public-key-only, zero-secret).

Copilot's findings

Files reviewed: 21/21 changed files
Comments generated: 3

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Copilot's findings

Files reviewed: 21/21 changed files
Comments generated: 1

bartonjs · 2026-05-13T16:17:29Z

        }
+
    }


Suggested change

}

}

}

}

Nit: stray blank line

bartonjs · 2026-05-13T18:41:21Z


+        [LibraryImport(Libraries.AppleCryptoNative, EntryPoint = "AppleCryptoNative_X25519DeriveRawSecretAgreementWithBytes")]
+        [UnmanagedCallConv(CallConvs = [ typeof(CallConvSwift) ])]
+        private static partial int AppleCryptoNative_X25519DeriveRawSecretAgreementWithBytes(


It feels a little strange that in Apple you called it WithBytes and in OSSL you called it WithPublicKey.

Doesn't really matter, but stood out as weird.

bartonjs · 2026-05-13T18:53:24Z

-                    Interop.AppleCrypto.X25519DeriveRawSecretAgreement(_key, publicKey, destination);
+                    Span<byte> publicKeyBuffer = stackalloc byte[PublicKeySizeInBytes];
+                    otherParty.ExportPublicKey(publicKeyBuffer);
+                    Interop.AppleCrypto.X25519DeriveRawSecretAgreementWithBytes(_key, publicKeyBuffer, destination);


Personally, I'd write it as export then call DeriveRawSecretAgreementCore, but the logic is simple, so 🤷

The JIT would probably eat the redundant call to ThrowIfPrivateNeeded.

bartonjs · 2026-05-13T18:56:08Z

+
+                    otherParty.ExportPublicKey(publicKeyBytes);
+
+                    using (SafeBCryptKeyHandle otherPartyKey = ImportPublicKey(publicKeyBytes, out _))


This one is a little bigger than the Apple/OSSL one, so I'll restate the "why not just defer to the other one?"

bartonjs · 2026-05-13T18:59:13Z

+
+            AssertExtensions.SequenceEqual(secret1, secret2);
+        }
+


It's probably also good to show that key1.DeriveRawSecretAgreement(key2) matches, if that isn't done elsewhere. (That imported and from-bytes are the same)

It's indirectly shown by trying the KATs through both forms, I guess?

bartonjs · 2026-05-13T19:07:50Z

                () => key.DeriveRawSecretAgreement(peer, new byte[X25519DiffieHellman.SecretAgreementSizeInBytes]));
        }

+        [ConditionalFact(nameof(IsNotStrictKeyValidatingPlatform))]
+        public void DeriveRawSecretAgreement_Bytes_ZeroSharedSecret_Throws()
+        {
+            // Wycheproof tcId 64: peer public key is a low-order point on Curve25519.
+            // This low-order point produces a shared secret that is all zeros.
+            byte[] privateKey = Convert.FromHexString("387355d995616090503aafad49da01fb3dc3eda962704eaee6b86f9e20c92579");
+            byte[] peerPublicKey = Convert.FromHexString("5f9c95bca3508c24b1d0b1559c83ef5b04445cc4581c8e86d8224eddd09f1157");
+
+            using X25519DiffieHellman key = ImportPrivateKey(privateKey);
+
+            Assert.ThrowsAny<CryptographicException>(() => key.DeriveRawSecretAgreement(peerPublicKey));


"Personally, I'd put these just as one test, showing that the same imported key throws for both forms."

"This is a more 'pure' test, no question, because it shows that this exception isn't just the previous exception being rethrown.."

These together lead to the open question "do we have any tests that show that (this kind of) exceptions don't taint the object?"

vcsjones added 5 commits May 11, 2026 20:56

Add DeriveRawSecretAgreement that accepts the public key as bytes

94b358e

Implement OpenSSL

8347d5f

Fix test build

8aef0d6

Byte-based key agreement for Windows

38a3aa3

Remove redundant method

35d0ccb

Copilot AI review requested due to automatic review settings May 12, 2026 16:52

Copilot started reviewing on behalf of vcsjones May 12, 2026 16:53 View session

github-actions Bot added the area-System.Security label May 12, 2026

dotnet-policy-service Bot assigned vcsjones May 12, 2026

Copilot AI reviewed May 12, 2026

View reviewed changes

Throw correct exception

4820cfd

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 12, 2026 17:29

Copilot started reviewing on behalf of vcsjones May 12, 2026 17:29 View session

Copilot AI reviewed May 12, 2026

View reviewed changes

Comment thread src/native/libs/System.Security.Cryptography.Native.Apple/pal_swiftbindings.swift

build-analysis Bot mentioned this pull request May 12, 2026

TestNativeDigits fails for ur-IN on Apple platforms (xunit v3 exposed previously non-running test) #125933

Open

vcsjones requested a review from bartonjs May 13, 2026 15:56

bartonjs reviewed May 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

X25519DiffieHellman agreement with byte-based public keys#128086

X25519DiffieHellman agreement with byte-based public keys#128086
vcsjones wants to merge 6 commits into
dotnet:mainfrom
vcsjones:x25519-agree-with-bytes

vcsjones commented May 12, 2026

Uh oh!

dotnet-policy-service Bot commented May 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

bartonjs May 13, 2026

Uh oh!

bartonjs May 13, 2026

Uh oh!

bartonjs May 13, 2026

Uh oh!

bartonjs May 13, 2026

Uh oh!

bartonjs May 13, 2026

Uh oh!

bartonjs May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-        }
-    }
+        }
+    }


		otherParty.ExportPublicKey(publicKeyBytes);

		using (SafeBCryptKeyHandle otherPartyKey = ImportPublicKey(publicKeyBytes, out _))

Conversation

vcsjones commented May 12, 2026

Uh oh!

dotnet-policy-service Bot commented May 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

bartonjs May 13, 2026

Choose a reason for hiding this comment

Uh oh!

bartonjs May 13, 2026

Choose a reason for hiding this comment

Uh oh!

bartonjs May 13, 2026

Choose a reason for hiding this comment

Uh oh!

bartonjs May 13, 2026

Choose a reason for hiding this comment

Uh oh!

bartonjs May 13, 2026

Choose a reason for hiding this comment

Uh oh!

bartonjs May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants